/**
 * Copyright 2006 gworks.com.au
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License. (http://www.apache.org/licenses/LICENSE-2.0)
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed 
 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for 
 * the specific language governing permissions and limitations under the License.
 *
 * <dhamma-message src="Atisha (11th century Tibetan Buddhist master)">
 * 	The greatest achievement is selflessness. The greatest worth is self-mastery.
 * 	The greatest quality is seeking to serve others. The greatest precept is continual awareness.
 * 	The greatest medicine is the emptiness of everything. The greatest action is not conforming with the worlds ways.
 * 	The greatest magic is transmuting the passions. The greatest generosity is non-attachment.
 * 	The greatest goodness is a peaceful mind. The greatest patience is humility.
 * 	The greatest effort is not concerned with results. The greatest meditation is a mind that lets go.
 * 	The greatest wisdom is seeing through appearances. 
 * </dhamma-message>
 */
package au.com.gworks.jump.system;

import java.util.Iterator;
import java.util.List;
import java.util.Map;

/**
 * <p>
 * Used by organisations to connect the system to their
 * directory implementations for the purpose of quering identities.
 * </p>
 * 
 * <p>
 * Why: The system is architected to be open. It requires the J2EE web-container to
 * establish the connection to the security realm for authentication. It also
 * uses the security realm for authorisation using the isUserInRole() that is
 * indirectly sourced from the HttpServletRequest object when invoked from the
 * web-tier. However, some views in the system need to be able to display identity
 * information based on the registered usernames.
 * </p>
 * 
 * <p>
 * When: Implement this interface when there is a directory available for
 * identity information to be sourced from.
 * </p>
 * 
 * <p>
 * How: Update the env.properties "identityQuerier" property to activate the
 * nominated implementation after placing the compiled implementation in the
 * JUMP_HOME/lib/ext directory
 * </p>
 * 
 * @see javax.servlet.http.HttpServletRequest#isUserInRole(String)
 * @see au.com.gworks.jump.system.DefaultIdentityQuerier
 * @see JUMP_HOME/conf/env.properties (identityQuerier)
 * @see JUMP_HOME/lib/ext
 */
public interface IdentityQuerier {
	/**
	 * A readonly identity whose data is sourced from a directory.
	 */
	public interface Entity {
		public String getUserId();
		public String getFirstname();
		public String getPreferredName();
		public Iterator getRoleNames();
		public String getSurname();
		public String getEmailAddress();
		public boolean isInRole(String roleName);
	}

	/**
	 * lookups a username from the directory and returns an entity
	 * representing that username.
	 * 
	 * @param username
	 *            is the username to user for the lookup
	 * @return a entity instance or null of not found
	 */
	public Entity lookup(String username);

	/**
	 * lookups a list of usernames from the directory and returns a map of
	 * entities that were queried.
	 *
	 * <p>
	 * When: there are many entities to query and the IdentityQuerier provider
	 * can improve performance by managing batches of requests.
	 * </p>
	 * 
	 * @param usernames
	 *            is the list of usernames to perform lookups on
	 * @return a map with keys being the username and values being the entity or
	 *         null if not found
	 */
	public Map lookup(List usernames);
}